6.8.áHost Interface Networking and bridging on Linux hosts

Before you proceed, please read Sectioná6.5, “Introduction to Host Interface Networking (HIF)”.

Note

There were some changes to the way dynamic host interface configuration is done in VirtualBox 1.4.0, due to changes in Linux kernel versions 2.6.18 and later. Also, this entire section of the manual was rewritten for Virtual 1.4.0. Please reread these sections if you used dynamic interfaces on earlier versions.

Since the Linux kernel has built-in support for virtual network devices (so-called TAP interfaces), VirtualBox on Linux makes use of these instead of providing custom host networking drivers. The TAP interfaces behave like physical network interfaces on your host and will work with any networking tools installed on your host system. From the point of view of the host, it looks like the guest's network card is connected to the TAP interface with a network cable. In order to use Host Interface Networking in VirtualBox, you must have access to the device /dev/net/tun. Check which group this device belongs to and make sure that any users who need access to VirtualBox Host Networking are members of this group. In most cases, this device will belong to the vboxusers group.

On Linux hosts, you have a choice of creating permanent networking interfaces which guests can attach to when they are created or having VirtualBox create a dynamic interface for a guest when the guest is started and remove it when the guest is stopped. Permanent interfaces are more suitable for hosts with a known set of guests that does not change often (such as some server setups), and they are easier to set up. Having VirtualBox create the interfaces dynamically provides more flexibility, but will normally require you to enter an administrator password each time an interface is created or removed.

6.8.1.áPermanent host interfaces and bridging

On Linux hosts, setting up a permanent host interface using bridging typically consists of three steps:

  1. First, you must create a bridge on the host and add one of the host's physical network interfaces to it, usually eth0. This will let you connect that interface to the virtual interfaces used by the virtual machines.

    Keep in mind that bridging is an Ethernet concept, not a TCP/IP one. In physical networking, bridging is normally used to connect two Ethernet networks, letting computers on the one communicate with computers on the other through a single point of contact without having to merge the networks into one.[12]

  2. For each guest network card that uses host interface networking, you must create a new "virtual" host interface (usually called vbox0 or similar) and add this interface to the bridge.

  3. Finally, specify the name of the new host interface in the settings of the virtual machine's virtual network card.

Unfortunately, Linux distributions differ substantially in how networking is configured. As we cannot provide instructions for all Linux distributions, we have restricted ourselves to describing how to set up bridging on Debian, Ubuntu, Fedora/Red Hat and openSUSE; in addition, we offer some generic instructions for advanced users.

VirtualBox ships with two utilities, VBoxAddIF and VBoxDeleteIF, which work on all distributions. These tools allow you to create and delete permanent host interfaces (which will automatically be recreated every time you boot your host computer) and optionally add them to an existing bridge. We also provide a utility called VBoxTunctl which you can use to create a temporary interface. These tools are described in Sectioná6.8.1.5, “Host Interface Networking utilities for Linux”. Even if you use plan to use host interfaces to create other networking setups than what we describe here, we recommend that you read the following instructions in order to get an understanding of how the interfaces work.

Some distributions -- such as Debian and Ubuntu -- have built-in tools to create host interfaces; you may also use those tools on those distributions.

6.8.1.1.áDebian and Ubuntu hosts

To set up a permanent host interface on a modern Debian or Ubuntu host, follow these steps:

  1. First install the bridge utilities (bridge-utils). package. You can do this from the command line as follows:

    sudo apt-get install bridge-utils
  2. Next, you must add an entry to the file /etc/network/interfaces to describe the bridge. The following sample entry creates a bridge called br0, adds the host ethernet interface eth0 to it and tells it to obtain an IP address using DHCP so that the host remains able to access the network.

    auto br0
    iface br0 inet dhcp
        bridge_ports eth0

    You will probably want to change this to suit your own networking needs. In particular, you may want to assign a static IP address to the bridge. You will find more documentation in the files

    1. /usr/share/doc/bridge-utilities/README.Debian.gz and

    2. /usr/share/doc/ifupdown/examples/network-interfaces.gz.

  3. Restart networking on the host:

    sudo /etc/init.d/networking restart

    After this the bridge will be recreated every time you boot your host system.

  4. Now, to create a permanent host interface called vbox0 (all host interfaces created in this way must be called vbox followed by a number) and add it to the network bridge created above, use the following command (see Sectioná6.8.1.5, “Host Interface Networking utilities for Linux” for more details):

    sudo VBoxAddIF vbox0 <user> br0

    Replace <user> with the name of the user who is supposed to be able to use the new interface.

    To tell VirtualBox to use the interface, select the virtual machine which is to use it in the main window of the VirtualBox application, configure one of its network adapters to use Host Interface Networking (using "Settings", "Network", "Attached to") and enter vbox0 into the "Interface name" field. You can only use a given interface (vbox0, vbox1 and so on) with a single virtual network adapter.

    Alternatively, you can use the VBoxManage command line tool (in this example we are attaching the interface to the first network card of the virtual machine "My VM"):

    VBoxManage modifyvm "My VM" -hostifdev1 vbox0

To set up a host interface using Debian and Ubuntu's native methods, do the following instead of step 4 above:

  1. First install the User Mode Linux utilities package (uml-utilities), which contains tools to create TAP interfaces. You can do this from the command line as follows:

    sudo apt-get install uml-utilities

    In order for VirtualBox to be able to access the interface, the user who will be running the virtual machine must be added to the group uml-net, for example with the following command (replace <user> with your user name):

    sudo gpasswd -a <user> uml-net

    You will have to log in again for the change to take effect.

  2. To describe the TAP interface to your Debian or Ubuntu system, add an entry to the file /etc/network/interfaces. This names the the interface and must also specify the user who will be running the virtual machine using the interface.

    The following sample entry creates the interface tap0 for the user <user> (again, replace with your user name):

    auto tap0
    iface tap0 inet manual
        up ifconfig $IFACE 0.0.0.0 up
        down ifconfig $IFACE down
        tunctl_user <user>

    You will probably want to change the entry based on your networking needs. The file /usr/share/doc/uml-utilities/README.Debian on your host computer will have additional documentation.

  3. To add the TAP interface to the bridge, replace the line

        bridge_ports eth0

    in the bridge section in /etc/network/interfaces with

        bridge_ports eth0 tap0
  4. Restart networking on the host:

    sudo /etc/init.d/networking restart

6.8.1.2.áBridging on openSUSE hosts

At least openSUSE 11 has a udev rule which calls /sbin/ifup for each network interface created with ifconfig. Calling ifup for host network interfaces will not work as the openSUSE system has no configuration about this interface (there is no /etc/sysconfig/network/ifcfg- file for this interface). Fortunately this rule has some exceptions, among them all interface names starting with tun and all interface names starting with tap. Therefore we will name the host interface tap0 in the following section.

The following instructions explain how to create bridge on openSUSE. Note that bridging on openSUSE hosts may not work properly if you are using NetworkManager to manage your network connections. To create a bridge on a recent openSUSE host, you must first install the bridge utilities (bridge-utils) package. If you are working from the command line this can be done as follows:

sudo /sbin/yast -i bridge-utils

Then you must create a text file describing the bridge to be created. The name of the file must correspond to the name of the bridge you wish to create. To create the bridge br0, you should call the file /etc/sysconfig/network/ifcfg-br0. Below we have given an example of a file which creates a bridge including the network device eth0, obtains an IP address by DHCP (through the network device) and is started automatically when openSUSE starts. You will probably want to adjust this to match your networking requirements.

BOOTPROTO='dhcp'
NETMASK='255.255.255.0'
STARTMODE='auto'
USERCONTROL='no'
DHCLIENT_TIMEOUT=30
BRIDGE='yes'
BRIDGE_PORTS='eth0'

For this example to work, you will also need to change the configuration for the network interface eth0 to a static IP address of 0.0.0.0, as openSUSE does not do this automatically when the interface is added to the bridge. You can do this using the graphical interface or by changing the following settings in the file /etc/sysconfig/network/ifcfg-eth-xx:xx:xx:xx:xx:xx, where the last part should be replaced with the hardware address of the network card.

BOOTPROTO='static'
IPADDR='0.0.0.0'

You can activate the bridge immediately after creating it with the command:

sudo /sbin/ifdown eth0
sudo /sbin/ifup br0

The bridge will be activated automatically from now on when the host is restarted.

Now, to create a permanent host interface called tap0 (all host interfaces created in this way must be called tap followed by a number) and add it to the network bridge created above, use the following command (see Sectioná6.8.1.5, “Host Interface Networking utilities for Linux” for more details):

sudo VBoxAddIF tap0 <user> br0

Replace <user> with the name of the user who is supposed to be able to use the new interface.

To tell VirtualBox to use this interface (tap0) for a virtual machine, select the VM in the main window, configure one of its network adaptors to use Host Interface Networking (using "Settings", "Network", "Attached to") and enter "tap0" into the "Interface name" field. You can only use a given interface (tap0, tap1 and so on) with a single virtual machine.

Alternatively, you can use the VBoxManage command line tool (in this example we are attaching the interface to the first network card of the virtual machine "My VM":

VBoxManage modifyvm "My VM" -hostifdev1 tap0

6.8.1.3.áBridging on Redhat and Fedora hosts

To create a bridge on Redhat and Fedora, you must first install the bridge utilities (bridge-utils) package. Then you must create a configuration file describing the bridge you wish to create. The following is the contents of an example configuration file /etc/sysconfig/network-scripts/ifcfg-br0, which sets the bridge br0 to get its IP address using DHCP and to start automatically when the system is started. You will probably want to adjust this to match your networking requirements.

DEVICE=br0
TYPE=Bridge
BOOTPROTO=dhcp
ONBOOT=yes

To add the network card eth0 to the bridge, add the following line to the end of the file /etc/sysconfig/network-scripts/ifcfg-eth0:

BRIDGE=br0

You can activate the bridge immediately after creating it with the command:

sudo /sbin/service network restart

The bridge will be activated automatically from now on when the host is restarted.

Now, to create a permanent host interface called vbox0 (all host interfaces created in this way must be called vbox followed by a number) and add it to the network bridge created above, use the following command (see Sectioná6.8.1.5, “Host Interface Networking utilities for Linux” for more details):

sudo VBoxAddIF vbox0 <user> br0

Replace <user> with the name of the user who is supposed to be able to use the new interface.

To tell VirtualBox to use this interface (vbox0) for a virtual machine, select the VM in the main window, configure one of its network adaptors to use Host Interface Networking (using "Settings", "Network", "Attached to") and enter "vbox0" into the "Interface name" field. You can only use a given interface (vbox0, vbox1 and so on) with a single virtual machine.

Alternatively, you can use the VBoxManage command line tool (in this example we are attaching the interface to the first network card of the virtual machine "My VM":

VBoxManage modifyvm "My VM" -hostifdev1 vbox0

6.8.1.4.áBridging with other distributions

Most modern Linux distributions provide their own way of setting up ethernet bridges. We recommend that you follow the instructions provided by your distribution to do this. For distributions which do not provide their own method of creating bridges, we provide generic instructions below. Please ensure that you thoroughly understand how your distribution's networking scripts work before following these instructions, as they involve making changes to your host network configuration in ways normally only done by the networking scripts, and as such may interfere with your network setup.

First of all, you will need to install the bridge utilities (usually named bridge-utils or similar). Once installed, as root, follow these instructions to create and configure a bridge:

  1. Create a new bridge with this command:

    brctl addbr br0
  2. If you are not using DHCP, run ifconfig and note down the network configuration of your existing network interface (e.g. eth0), which we will need to copy to the bridge in a minute.

  3. Remove the IP address configuration from the existing network device (e.g. eth0) with:

    ifconfig eth0 0.0.0.0 

    Warning: You will lose network connectivity on eth0 at this point.

  4. Add your network adapter to the bridge:

    brctl addif br0 eth0
  5. Transfer the network configuration previously used with your physical ethernet adapter to the new bridge. If you are using DHCP, this should work:

    dhclient br0

    Otherwise, run ifconfig br0 x.x.x.x netmask x.x.x.x and use the values that you noted down previously.

  6. To create a permanent host interface called vbox0 (all host interfaces created in this way must be called vbox followed by a number) and add it to the network bridge created above, use the following command (see Sectioná6.8.1.5, “Host Interface Networking utilities for Linux” for more details):

    VBoxAddIF vbox0 <user> br0

    Replace <user> with the name of the user who is supposed to be able to use the new interface.

6.8.1.5.áHost Interface Networking utilities for Linux

Although Linux comes with built-in support for virtual networking interfaces, there are not many programs available for managing these. VirtualBox supplies three tools for this purpose: VBoxAddIF, VBoxDeleteIF and VBoxTunctl. The last of these is in fact the tunctl utility from the User Mode Linux project. In this section, we describe how to use these utilities.

VBoxAddIF creates a permanent TAP interface which does not go away when the host system is restarted. This interface should be called vbox0, vbox1 or similar. The following command creates the interface vbox0 for the user <user> and adds it to the bridge br0. If you do not wish to add the interface to a bridge, you can leave off the bridge name.

sudo VBoxAddIF vbox0 <user> br0

Change the interface, user and bridge names to fit your own setup.

To remove an interface which you have created with VBoxAddIF, use the following command. Replace vbox0 with the name of the interface.

sudo VBoxDeleteIF vbox0

To create a temporary TAP interface which will disappear when the host system is restarted, use the VBoxTunctl command. The following example creates the interface vbox0 for the user <user>:

sudo VBoxTunctl -t vbox0 -u <user>

If you have installed the bridge utilities (see the preceding sections), you can add this temporary interface to an Ethernet bridge using the command

sudo brctl addif br0 vbox0

Replace br0 with the name of the bridge and vbox0 with the name of the interface. Before you can use the interface, you will still need to make it active (or "bring it up" in networking terminology, usually using the standard Linux ifconfig utility) and configure it with an IP address and related information. To remove a temporary interface, do the following, replacing vbox0 with the name of the interface to be removed:

sudo VBoxTunctl -d vbox0

6.8.2.áCreating interfaces dynamically when a virtual machine starts up

As an alternative to the permanent interfaces described previously, you can tell VirtualBox to execute commands (usually scripts) to set up your network dynamically, every time a virtual machine starts or stops. This is normally done in order to create the TAP interfaces at VM startup time, although you can also use this feature to configure existing interfaces. If you are not using permanent interfaces then the startup command should write the name of the interface which it has created, typically something like tap0 or tap2, to its standard output (the VBoxTunctl -b command does exactly this) and the command executed when the machine stops should remove the interface again.

The commands and scripts used will depend on the networking configuration that you want to set up. Both commands are given a file descriptor to the Linux TAP device as their first argument (this is only valid if the virtual machine is using previously created interfaces) and the name of the interface, if it is known, as the second argument. In most circumstances, you will only want to use the second argument.

Here is an example of a set up script which creates a TAP interface and adds it to the network bridge br0.

#!/bin/bash

# Create a new TAP interface for the user 'vbox' and remember its name.
interface=`VBoxTunctl -b -u vbox`

# If for some reason the interface could not be created, return 1 to
# tell this to VirtualBox.
if [ -z "$interface" ]; then
exit 1
fi

# Write the name of the interface to the standard output.
echo $interface

# Bring up the interface.
/sbin/ifconfig $interface up

# And add it to the bridge.
/sbin/brctl addif br0 $interface

If this script is saved as /home/vbox/setuptap.sh and made executable, it can be used to create a TAP interface when a virtual machine is started, by configuring one of the machines network adapters to use Host Interface Networking (without specifying a device in the "Interface Name" field) and entering gksudo /home/vbox/setuptap.sh into the "Setup Application" field (replace gksudo by kdesu, or whatever is appropriate for your system). Alternatively you can use the the VBoxManage command line tool (in the following example for a machine called "Linux VM"):

VBoxManage modifyvm "Linux VM" -tapsetup1 "gksudo /home/vbox/setuptap.sh"

An example of a matching script to remove the interface from the bridge and shut it down would be:

#!/bin/bash

# Remove the interface from the bridge.  The second script parameter is
# the interface name.
/sbin/brctl delif br0 $2

# And use VBoxTunctl to remove the interface.
VBoxTunctl -d $2

If this is saved as /home/vbox/cleanuptap.sh and made executable, the virtual machine can be told to execute it when it shuts down by entering gksudo /home/vbox/cleanuptap.sh, into the "Termination Application" field in VirtualBox's network configuration settings, or by using VBoxManage:

VBoxManage modifyvm "Linux VM" -tapterminate1
"gksudo /home/vbox/cleanuptap.sh"

Note

The VBoxSDL front end to VirtualBox (see Sectioná7.3, “VBoxSDL, the simplified VM displayer”) allows for an additional way of configuring TAP interfaces if it is started from a custom parent process. This parent process can allocate the required TAP interfaces and let VirtualBox inherit the file handles. For this to work, the file descriptor has to be passed to VBoxSDL using the option -tapfd<N> <fd>. In this case, the setup and termination scripts will not be called.



[12] A useful introduction to bridging can be found here: http://gentoo-wiki.com/HOWTO_setup_a_gentoo_bridge. While this is targeted at a Gentoo system, it contains a useful generic introduction.